ODCanvas

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODCanvas

Superclasses
ODObject
Subclasses
none

An object of the ODCanvas class is a wrapper for a graphics-system-specific drawing structure that represents a drawing environment--the environment for constructing an image.

Description
A canvas object represents a drawing environment--the destination for drawing calls--for any of the available graphics systems that your part uses. Your part uses the standard platform drawing calls for your graphics system to render its content on a canvas. A canvas can refer to anything a graphics system knows how to draw into; for example, a graphics port, print job, offscreen pixel buffer, bitmap, structured display list, or stream of PostScript(TM) code. A graphics-system-specific drawing structure may retain state information (for example, pen color) that influences how the drawing calls are interpreted.
Your part creates a canvas object by calling the window-state object's CreateCanvas method (page 856). To create a canvas to attach to a particular facet, your part can call that facet's CreateCanvas method (page 237).
Each canvas object includes one or more graphics-system-specific drawing structures, which are not deleted when the canvas is released. If you create a canvas, you must separately create the underlying drawing structure, and you are responsible for deleting that drawing structure when the canvas is released.
For more information on the graphics systems available on the Mac OS platform, see Inside Macintosh: Imaging with QuickDraw and Inside Macintosh: QuickDraw GX Graphics.

Canvas Characteristics
A canvas must be either dynamic or static:

A dynamic canvas is a drawing canvas that is interactive. Windows, which can be scrolled or paged to display different portions of a part's content, are good examples of dynamic canvases.
A static canvas is a drawing canvas that cannot be changed once it is rendered; for instance, one that cannot be scrolled. A printed image (or onscreen print preview) is an example of a static canvas because the user cannot scroll elements on the page or otherwise interact with it once it is drawn.

Your part can display parts differently based on this distinction. For example, you might use scroll bars on the screen but not on printed material. You might also use different drawing calls for printing than for screen display because printing varies from platform to platform.
A canvas is also defined as being either onscreen or offscreen:

An onscreen canvas is the main canvas of the window or print job.
An offscreen canvas is used to improve performance by allowing you to draw a complex image to an offscreen cache, and then quickly transfer the completed image to the onscreen canvas, with full freedom to alter or distort the image in the process. For instance, you can create an offscreen canvas to do double-buffering or image manipulation (such as changing the tinting or translucency of an image).

When a part creates a canvas it specifies, for the lifetime of the canvas, whether the canvas is dynamic or static and whether it is onscreen or offscreen.
A canvas is further defined in terms of a transformation matrix and its coordinate bias:

A transformation matrix called the bias transform describes the transform that is applied to measurements in a canvas's coordinate space to change them into standard platform-normal coordinates.
The coordinate bias, defined by the bias transform, is the difference between the canvas's coordinate space and the standard platform-normal coordinate space. The coordinate bias usually takes the form of an offset in the origin, a change in the polarity of one or more axes, and possibly a change in scale.

Offscreen Imaging
Canvases can be attached to individual facets. If a particular facet in a window's facet hierarchy has an attached canvas, it and all its embedded facets (and their embedded facets, and so on) draw to that canvas. Each facet inherits its canvas from its containing facet; the inherited canvas is called the parent canvas. For most drawing, only a window's root facet needs a canvas.
If a particular part needs an offscreen canvas, however, it can attach a canvas to one of its facets on a display frame. The canvas has a reference to that facet and also a reference to the part that created the canvas and attached it to a facet--the owning part. The reference enables the canvas to notify the owning part that its content has changed and that it needs to be updated. The owning part is responsible for copying the image of the offscreen canvas to its parent canvas during updates.
The owning part of a canvas need not be the same as its facet's part. For instance, a containing part may customize the drawing of an embedded part by assigning the facet of the embedded part to an offscreen canvas. In this case, the containing part must make itself the owning part so that it can control the drawing of the facet on the screen.
For added convenience, offscreen canvases maintain updating information that mirrors their onscreen equivalents. This lets embedded parts interact with their drawing environment in a consistent manner, whether the parts are displayed in the window canvas or in an offscreen canvas.

Methods
This section presents summary descriptions of the ODCanvas methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Canvas Characteristics

AcquireBiasTransform
Returns a reference to the bias transform associated with this canvas.
SetBiasTransform
Assigns the specified bias transform to this canvas.
GetFacet
Returns a reference to the facet associated with this canvas.
SetFacet
Assigns the specified facet to this canvas.
AcquireOwner
Returns a reference to the part that owns this canvas.
SetOwner
Assigns the specified owning part to this canvas.
IsDynamic
Returns a Boolean value that indicates whether this canvas is dynamic.
IsOffscreen
Returns a Boolean value that indicates whether this canvas is offscreen.
Drawing Structures

GetPlatformCanvas
Returns the drawing structure for the specified graphics system for this canvas.
SetPlatformCanvas
Assigns the drawing structure for the specified graphics system to this canvas.
HasPlatformCanvas
Returns a Boolean value that indicates whether this canvas has or can generate a drawing structure for the specified graphics system.
GetGXViewPort [M]
Returns the QuickDraw GX view port drawing structure for this canvas.
GetQDPort [M]
Returns the QuickDraw graphics-port drawing structure for this canvas.
Invalidating and Updating

AcquireUpdateShape
Returns a reference to the shape object defining the area of this canvas that needs to be updated.
ResetUpdateShape
Sets the update shape for this canvas to the empty shape.
Invalidate
Adds the specified area to the update shape for this canvas, ensuring that the specified area of this canvas is updated.
Validate
Subtracts the specified area from the update shape for this canvas.
Printing

GetPlatformPrintJob
Returns the print job for the specified graphics system for this canvas.
SetPlatformPrintJob
Assigns the print job for the specified graphics system to this canvas.
HasPlatformPrintJob
Returns a Boolean value that indicates whether this canvas has a print job for the specified graphics system.

Methods
AcquireBiasTransform
AcquireOwner
AcquireUpdateShape
GetFacet
GetGXViewport
GetPlatformCanvas
GetPlatformPrintJob
GetQDPort
HasPlatformCanvas
HasPlatformPrintJob
Invalidate
IsDynamic
IsOffscreen
ResetUpdateShape
SetBiasTransform
SetFacet
SetOwner
SetPlatformCanvas
SetPlatformPrintJob
Validate